Hcs Logging Support 



All log records are classified using an ASN. 1 Object Id. 



Standard Log record ASN. 1 Type Classification: 



1.x - All log records 

l.x.O - NonCritical 

l.x.0.0 - Trace output 

l.x.O. 1 - Progress 

1.x. 1 - Error 

l.x.2 - Warning 



Log records are composed of four fields of information: type, time, creator, 
information. Type and time are ASN. 1 ids while the creator can be either an 
ASN. 1 HcsResource instance id or a text string. The information field is the 
actual text generated by the logging component. 

The are various components in the system that are responsible for the 
collecting, storage, and possible forwarding of log records. All forms of 
this component are modeled by the HcsLogFacility class. 

HcsLogFacility class 
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The HcsLogFacility class is an HcsResource derivations who's purpose is to 
provide storage and forwarding at various levels in the system. There are 
currently two implementations: the Local Log Facility, and the Central Log 
Facility. The HcsLogFacility interface is: 

class HcsLogFacility : public HcsResource 
{ 

public: 



virtual HRESULT putRecord ( char* typeAsnlldStrPtr, 

char* timeAsnlStrPtr, 
char* idStrPtr, 
char* recordPtr ) = 0; 

} 

The Local Log Facility 

An Local Log Facility (LLF) instance exists in every node in the 

system. The purpose of this HcsLogFacility implementation is to accept all 
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log records from various HCS components on that node and to buffer them in a 
large circular on disk until they can be delivered to the Central Log 
Facility (CLF). The intent is that a node could survive for some time if the 
CLF were to be unavailable. One of the configuration parameters passed to 
each Local HcsLogFacility instance will be the resource name of the 
HcsLogFacility through which that instance is to forward its records. The 
current thinking is that this will be the name of the CLF but this is not an 
architectural requirement. In other words there could be intermediate- levels 
of HcsLogFacilities placed in the system. In fact on LLF could be configured 
to forward its records to another LLF. After all a HcsLogFacility is a 
HcsLogFacility. 

The Central Log Facility 

There will be one instance of the Central Log Facility (CLF) instance in the 
entire system. The purpose of this HcsLogFacility implementation is to 
accept all log records from various HCS components within the entire system 
and to provide for the final storage of this information. The intent is that 
this facility provide for the long term, offline, archival of the entire 
HCS system log. In addition to this function, it will also provide for the 
on-line viewing of some portion of the log. 
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How log records are written 



So the question is: how do HCS components log there information? To provide 
a standard and safe access to the HcsLogFacilites, there is a class family 
provided. The family is based at a class called HcsLogPort. This class 
implements the common behavior of all types of LogPorts and is functional on 
its own. 

Derived from the HcsLogPort are the HcsResourceLogPort and 
HcsLogFacilityPort classes. The HcsResourceLogPort provide easy support for 
the resource developer while the HcsLogFacilityPort provides direct access 
to HcsLogFacilites. In general, the first is used by Resource derivations 
while the second would be used by resource servers and system components. 

class HcsLogPort 

{ 

public: 

/* Global Constant AsnObjectlds for all defined log record types — 
SEE INCLUDE FOR TYPE LIST */ 
#include <HcsLogRecTypes.h> 

public: 

HcsLogPort ( char* idStrPtr ) ; 
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virtual -HcsLogPort ( void ); 

void put ( const AsnlObjectld* typePtr, char* formatStrPtr, ... ) ; 
inline char* getldStrPtr ( void ) { return( myldStrPtr ); }; 
BOOL setldStr ( char* newIdStrPtr ); 

/* Methods to control log filtering */ 
void enable ( char* asnlldOfLogRecTypeToEnablePtr ); 
void disable ( char* asnlldOfLogRecTypeTobisablePtr ); 
BOOL isEnabled ( char* asnlldOfLogRecTypeToChkPtr ); 
BOOL isEnabled ( const AsnlObjectld* logRecTypeToChkPtr ); 
inline HRESULT dumpFilterState ( TextSink* toSinkPtr, int 
maxLineSize ) 

{ return( myFilter.dumpState( toSinkPtr ) ); }; 
inline void resetFilter ( void ) { myFilter.resetQ; }; 



void forwardRec ( const AsnlObjectld* typePtr, char* timeAsnlStrPtr, 
char* idStrPtr, char* recordPtr ) ; 

/* used to forward from one 
HcsLogPort implementation to another */ 

protected: 

/* Derivation Interface */ 
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/* Defaults to writing errors only to the NT SystemLog */ 
virtual void dumpRec( const AsnlObjectld* typePtr, char* 
timeAsnlStrPtr, char* idStrPtr, char* recordPtr ) ; 

private: 

void putOver ( void ) ; 

HcsLogPort ( void ) ; 

void* operator new ( size t size ) ; 

myldStrPtr; 

myHandle; 
myldEvent; 
myFilter; 

public: 

/* Grand fathered Methods */ 
void setTrace ( BOOL to ); 
void setProgress ( BOOL to ); 
void setWarning ( BOOL to ); 
BOOL isTraceEnabled ( void ); 
BOOL isProgressEnabled ( void ); 
BOOL isWarningEnabled ( void ); 



private: 

char* 
HANDLE 
DWORD 
AsnlSet 
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void putError ( char* formatStrPtr, ... ) ; 
void put Warning ( char* formatStrPtr, ... ) ; 
void putTrace ( char* formatStrPtr, ... ) ; 
void putProgress ( char* formatStrPtr, ... ) ; 
void putMaintFailure ( char* formatStrPtr, ... ) ; 

}; 

/* class used by resource implementors */ 
class HcsResourceLogPort : public HcsLogPort 

{ 

public: 

HcsResourceLogPort ( HcsResourcelmp* ownerPtr, char* idStrPtr ); 
virtual -HcsResourceLogPort ( void ); 

protected: 

/* routes all output through the owning HcsResourcelmp's 
putLogRecord private support method */ 

void dumpRec( char* typeAsnl IdStrPtr, char* timeAsnlStrPtr, char* 
idStrPtr, char* recordPtr ); 

private: 

HcsResourceLogPort ( void ); 
void* operator new ( size t size ); 
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/* class used by non resource centric implementations */ 
class HcsLogFacilityPort : public HcsLogPort 

{ 

public: 

HcsLogFacilityPort ( char* idStrPtr ); 

HcsLogFacilityPort ( HcsLogFacility* facilityPtr, char* idStrPtr ); 

HRESULT setFacility ( HcsLogFacility* facilityPtr ); 

HRESULT clearFacility ( void ); 

BOOL isFacilitySet ( void ); 
inline BOOL isTapped ( void ) { return( mylsTapped );"}; 
inline void setTapOn ( void ) { mylsTapped = TRUE; }; 
inline void setTapOff ( void ) { mylsTapped = FALSE; }; 

virtual -HcsLogFacilityPort ( void ); 
protected: 

/* defaults to writing errors only to the NT SystemLog (chicago??) 
unless an HcsLogFacility is made available 
and is functioning */ 
void dumpRec ( const AsnlObjectld* typePtr, char* timeAsnlStrPtr, 
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char* idStrPtr, char* recordPtr ) ; 



private: 

HcsLogFacilityPort ( void ) ; 

void* operator new ( sizet size ) ; 
private: 

HcsLogFacilityOlePtr myFacOlePtr; 
BOOL" mylsFacSet; 
BOOL mylsTapped; 

}; 

Effects on the HcsResourcelmp Interface 

HcsResourceImp::putLogRecord implementation: keeps and internal 
HcsLogFacilityPort instance which is used to forward records through. 
Before a record is actually forwarded, HcsResourcelmp checks to make sure an 
HcsLogFacility has been assign to its port. If this is not the case, an 
attempt is made to locate the local HcsLogFacility for that node via the 
HcsResrcBusIf::locateLocalResourceById method (new). In any case, the log 
record is written to the via the resource instance's HcsLogFacilityPort. 

New: The HcsResource interface defines, and the HcsResourcelmp 
implements, 

two methods: 



[/STANDARD.02] 



-9- 



5/28/99 



HRESULT enableLogging ( [in, string]char* forLogRecClassPtr ); 
HRESULT disableLogging ( [in, string]char* forLogRecClassPtr ); 

These are used by support to enable and disable logging dynamically within 
instances of HcsResources. 

The HcsLogFacility class and HcsLogFacilityPorts 

Notice that any HcsLogFacility can be referenced by a HcsLogFacilityPort. 
This means that some components may wish to connect directly to the CLF. A 
good example of this may be the Resource Bus Manager (RBMGR.EXE). 
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